Skip to content

fix: grid3d's pygbag page starts in 3D and keeps the 2D view safe, for 0.5.1 - #82

Merged
dmccoystephenson merged 1 commit into
mainfrom
fix/web-template-lazy
Nov 20, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
fix/web-template-lazy

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

The browser page made by grid3d.web.templatePath() now starts in 3D, as a desktop Grid3DView game does. Problems found in a game's run of the 0.5.0 template are also fixed. The version is bumped to 0.5.1.

3D by default

  • On a page that starts in 3D, the relay's scripts and engine are loaded right away, alongside pygbag.
  • The starting view is chosen in this order:
    1. ?view=2d or ?view=3d in the address (for testing and sharing; not remembered).
    2. The player's last choice on the button, kept in localStorage. Every storage access is wrapped in try/catch, and a stored 2D wins over the default.
    3. The game's default: the button's data-default-view. It is 3d unless the game is built with templatePath(defaultView="2d"), which writes a 2D-first copy of the template.
  • The 2D canvas is hidden only once the game has sent the 3D view something to draw. Until then the relay canvas stays invisible and lets presses through, so pygbag's loading and tap-to-start screens stay usable while 3D loads.
  • If 3D can't start (no WebGL 2, a file missing, over the size limit, the engine failed), the 2D view stays. The button then reads 3D unavailable, and a note under it says why in plain words; Strata's failure codes such as network are translated. The note stays until 10 seconds after the player's next press or key, or until it is tapped.
  • Strata's own loading and failure overlay is hidden. It covered the whole 2D game when the engine failed.

Fixes

  1. Relay scripts on every page. strata-loader.js, strata-kit.js and grid-relay.js (about 58 KB) were in the page's markup. They are now injected, in order, only when 3D is wanted, so a page that starts in 2D downloads nothing of the 3D view. Graphik3D.wanted() (wants3D()) turns true only once they are in, so Grid3DWebView.open() never runs before the relay exists.
  2. The button pushed off screen on phones. The page is kept from scrolling (overflow: hidden on html and body), so a phone's browser can't widen it to fit pygbag's 50000-pixel measuring element. The relay canvas is sized 100% instead of 100vw.
  3. Duplicate viewport tag. pygbag's two viewport tags, the second of which replaced the first's width=device-width, are merged into one.
  4. The button over a game's HUD. Graphik3D.area() and grid3d.web.buttonArea() give the button's (x, y, width, height) in CSS pixels, the units of the web view's labels and panels. A game can then keep its HUD text out from under the button. A game-side layout was chosen over moving the button: no corner is free in every game, and the game knows its own layout.

Sizes (ophidian's build, files fetched by the default page; gzip at the default level)

Page Raw Gzipped
0.5.0 template, 2D-first (with the three relay scripts) 208,939 B 159,247 B
0.5.1, default load (3D: page, scripts, 1.05 MB wasm, 206 KB glue, game) 1,471,924 B 540,644 B
0.5.1, a 2D page (?view=2d or a remembered 2D) 160,548 B 144,219 B

Testing

  • pytest: 319 passed, 2 skipped. The new tests cover the template's contents (scripts injected in order rather than in the markup, the starting-view order, storage in try/catch, 2D hidden only once 3D is fed, the failure note, the Strata overlay hidden, one viewport tag, no scrolling, no Jinja delimiters in graphik's part), templatePath(defaultView), buttonArea() and parseArea().
  • ophidian's pygbag build with this template was run end to end in Chromium at 390x844, DPR 3 with touch: 45/45 checks passed twice. The default load lands in 3D with no press. Keys, swipes, taps, the shop, pause and death all work in 3D, with the button on screen and no text under it. Switching to 2D is remembered across a reload, and nothing of 3D is fetched then. ?view=2d starts in 2D and fetches no relay file, and its button still loads 3D. With grid-relay-scene.wasm or grid-relay.js blocked, the page falls back to 2D, shows the reason, and the game keeps running. The 0.5.0 template fails five of these checks.

drafted by Claude on behalf of Daniel Stephenson

🤖 Generated with Claude Code

…r 0.5.1

The browser page now starts in 3D, as a desktop Grid3DView game does,
and the problems found in a game's run of the 0.5.0 template are fixed.

- 3D by default: the relay's scripts and engine are loaded at once,
  alongside pygbag. The starting view is taken from ?view=2d / ?view=3d
  in the address (not remembered), else the player's last choice on the
  button (localStorage, every access in try/catch; a stored 2D wins),
  else the game's default: the button's data-default-view, "3d" unless
  the game builds with templatePath(defaultView="2d").
- The 2D canvas is hidden only once the game has sent the 3D view
  something to draw, and the relay canvas stays invisible (and lets
  presses through) until then, so pygbag's loading and tap-to-start
  screens stay usable while 3D loads.
- If 3D can't start (no WebGL 2, a file missing, too big, the engine
  failed), 2D stays, the button reads "3D unavailable" and a note under
  it says why in plain words (Strata's failure codes are translated).
  Strata's own loading/failure overlay is hidden; it covered the 2D game.
- The relay's three scripts (about 58 KB) are no longer in the page's
  markup; they are injected, in order, when 3D is wanted, so a page
  starting in 2D fetches nothing of the 3D view. Graphik3D.wanted()
  (wants3D()) turns true only once they are in.
- The page is kept from scrolling (overflow: hidden on html and body),
  so a phone's browser can no longer widen it to fit pygbag's
  50000-pixel measuring element and push the 2D/3D button off screen;
  the relay canvas is sized 100% rather than 100vw.
- pygbag's two viewport tags, the second of which replaced the first's
  width=device-width, are merged into one.
- Graphik3D.area() and grid3d.web.buttonArea() give the button's
  (x, y, width, height) in CSS pixels, so a game's HUD can keep its text
  out from under it.

Template content checks and tests for templatePath(defaultView),
buttonArea() and parseArea() are added; the version is 0.5.1 and the
README's browser section describes the above.

drafted by Claude on behalf of Daniel Stephenson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LYNeuoCqxFpUXrFhxnTg89
@dmccoystephenson
dmccoystephenson merged commit faa282c into main Nov 20, 2026
6 checks passed
@dmccoystephenson
dmccoystephenson deleted the fix/web-template-lazy branch November 20, 2026 14:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant